home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / CGAMEJOY.ARJ / JOYSTICK.DOC next >
Text File  |  1992-01-10  |  20KB  |  494 lines
  1. JOYSTICK.ZIP                                                Wed  01-08-1992
  2.  
  3.  
  4.                        C Game Adapter Library
  5.  
  6.                              Rev 1.2
  7.  
  8.                                 by
  9.  
  10.                            Ed Torgerson
  11.  
  12.                           CIS     70313,456
  13.                           GEnie   E.TORGERSON1.
  14.                           BIX     etorgerson
  15.  
  16.  
  17.         A mixed language C and Assembler library of routines for
  18.         accessing the IBM PC game adapter at port 201h.
  19.         Object-Ready, Event-ready design featuring inter-module
  20.         data hiding. (should be easy to change it to a C++ class)
  21.  
  22.         The low level module is mostly asm statements, but the
  23.         provided small model library module should allow anyone
  24.         with TURBOC 2.0, TURBO C++, or Borland C++ to use it,
  25.         with or without an assembler.  If you need a straight
  26.         C replacement for my low level routines, look at JOY.ARC
  27.         in the Borland C Forum in BPROGB on Compuserve.
  28.  
  29.         Pseudocode/Structured English modules are also included
  30.         to aid in adapting to other languages.
  31.  
  32. /*-------------------------------------------------------------------*/
  33.  
  34.    Files:
  35.        joystklo.c      low level generic game adapter port routines
  36.        joystkmd.c      joystick-specific middle level functions
  37.                            built on top of joystklo.c
  38.        joystick.h      header file for joystklo.c, joystkmd.c
  39.                            and joystk_m.lib
  40.        joystk_s.lib    an already compiled small model library
  41.                            consisting of joystklo.c and joystkmd.c
  42.        testlow.c       a small demonstration of joystklo.c
  43.        testmid.c       a small demonstration of joystkmd.c
  44.        joystklo.se     pseudocode/structured english
  45.        joystkmd.se     pseudocode/structured english
  46.  
  47. /*-------------------------------------------------------------------*/
  48.  
  49.     JOYSTKLO.C provides generic low level game-adapter port functions to:
  50.  
  51.                1.  detect the presence of a game adapter
  52.                2.  verify which axes are functional
  53.                3.  read current button status
  54.                4.  read changed button status
  55.                5.  read current resistive axis position
  56.                6.  allow change of active axes within this system
  57.                    as long as they have been found functional.
  58.  
  59.  
  60.    JOYSTKMD.C provides middle level joystick-specific functions to:
  61.  
  62.                1.  detect and initialize a joystick coordinate system.
  63.                2.  read changed joystick position
  64.                3.  provide a rough translation from the top-left origin
  65.                    joystick coordinate system to a balanced 0,0
  66.                    centered cartesian system
  67.                4.  get/reset joystick center coords
  68.                5.  get/reset joystick minimum coords
  69.                6.  get/reset joystick maximum coords
  70.                7.  get/set an ignore threshold (tolerance) for
  71.                    reading changed joystick positions
  72.  
  73. /*-------------------------------------------------------------------*/
  74.  
  75. Background:      
  76.  
  77.         What I wanted was a decent usable library of functions
  78.     that did a little more than just read the raw port input.
  79.     I don't really use the adapter port that much, but I like
  80.     to cover my bases when it comes to my library.  I've tried
  81.     to make it fairly simple, but fairly versatile.
  82.  
  83.         The low level module is not joystick specific, so you
  84.     should be able to use it with any other periferal that uses
  85.     the game adapter.  It's coded with assembly statements to make
  86.     the loops a little faster which should be more useful inside
  87.     timer interrupt 1Ch. I didn't really try too hard to optimize
  88.     it, so you should be able to throw it into pure assembly and
  89.     knock a couple of cycles off of it fairly easily.
  90.  
  91.         I did try to make the middle level module flexible enough
  92.     to use a joystick as a practical pointing device in either a
  93.     polled or an event-driven architecture.  You may want to
  94.     change the ignore threshold system that I've set up to
  95.     compensate for the non-linear scaling of the joystick.  You
  96.     may also want to take a look at my cartesian coordinate
  97.     system.  I've set it up for a center-oriented scale.  Although
  98.     I can't imagine why you might want a different orientation,
  99.     I don't claim to be omniscient, so the translation is performed
  100.     by a seperate function.  If your preference differs from mine,
  101.     you can easily just plug in your own function.
  102.  
  103.         I've done limited testing on an old IBM XT 5160 model 267
  104.     with 11/08/82 BIOS as well as my PS/2 like 386 AT and haven't
  105.     found anything, yet..........................................
  106.  
  107.     If you find this library useful, donate to your favorite cause.
  108.  
  109.     I just want to thank Gary Blaine for putting JOY.ARC out here,
  110.     my function for reading position is based on his.
  111.  
  112.         These modules are hereby released to the public domain
  113.         by Ed Torgerson : CIS 70313,456,  GEnie E.TORGERSON1.
  114.  
  115.             Any constructive correspondence is welcome.
  116.  
  117. /*-------------------------------------------------------------------*/
  118.  
  119. port 201h :
  120.  
  121.            bit             JOYSTICK                PADDLE
  122.            ---             --------                ------
  123.            7               B  button 2             D button
  124.            6               B  button 1             C button
  125.            5               A  button 2             B button
  126.            4               A  button 1             A button
  127.            3               B  y-axis               D Coordinate
  128.            2               B  x-axis               C Coordinate
  129.            1               A  y-axis               B Coordinate
  130.            0               A  x-axis               A Coordinate
  131.  
  132. /*-------------------------------------------------------------------*/
  133. /*--------------------- Low Level Functions -------------------------*/
  134. /*-------------------------------------------------------------------*/
  135.                     
  136. JstDetect :
  137.  
  138.     purpose:    Detect active game port axes.
  139.  
  140.     syntax:     int  JstDetect ( void ) ;
  141.  
  142.     remarks:    performs check by reading port 201h, triggering the
  143.                 one-shot timers and immediately checking for bits
  144.                 that have changed.  It also sets up valid and
  145.                 active axes.
  146.  
  147.     returns:    bit mask of valid axes in original port format.
  148.                 values can be easily checked by ANDing this value
  149.                 with the defined macros:
  150.  
  151.                             JOYSTICK_A, JOYSTICK_B
  152.                     JAX_AXIS, JAY_AXIS, JBX_AXIS, JBY_AXIS
  153.           
  154. /*-------------------------------------------------------------------*/
  155.  
  156. JstGetButton :
  157.  
  158.     purpose:    returns the current button value.
  159.  
  160.     syntax:     int  JstGetButton ( void ) ;
  161.  
  162.     remarks:    This is not just a straight read of port 201h.
  163.                 It is intended to provide quick determination
  164.                 of the current status using macros.
  165.  
  166.     returns:    bit mask of current button state.
  167.                 values can be easily checked by ANDing this
  168.                 value with the defined macros:
  169.  
  170.            JA1_BUTTON_DOWN, JA1_BUTTON_UP,
  171.            JA2_BUTTON_DOWN, JA2_BUTTON_UP
  172.            JB1_BUTTON_DOWN, JB1_BUTTON_UP,
  173.            JB2_BUTTON_DOWN, JB2_BUTTON_UP
  174.            J_ANY_BUTTON_DOWN
  175.            J_A_BUTTON_DOWN, J_B_BUTTON_DOWN
  176.            J_BUTTON_1_DOWN, J_BUTTON_2_DOWN
  177.  
  178.            bit      STATE        JOYSTICK           PADDLE
  179.            ---      -----        --------           ------
  180.            7        down         B  button 2        D button
  181.            6        down         B  button 1        C button
  182.            5        down         A  button 2        B button
  183.            4        down         A  button 1        A button
  184.            3         up          B  button 2        D button
  185.            2         up          B  button 1        C button
  186.            1         up          A  button 2        B button
  187.            0         up          A  button 1        A button
  188.  
  189. /*-------------------------------------------------------------------*/
  190.  
  191. JstGetChangedButton
  192.  
  193.     purpose:    returns any change in button state since
  194.                 the last call to either JstGetChangedButton
  195.                 or JstGetButton.
  196.  
  197.     syntax:     int  JstGetChangedButton( void ) ;
  198.  
  199.     remarks:    see JstGetButton
  200.  
  201.     returns:    see JstGetButton
  202.  
  203. /*-------------------------------------------------------------------*/
  204.  
  205. JstGetPosition  :
  206.  
  207.     purpose:    returns the position of the given axis.
  208.  
  209.     syntax:     int  JstGetPosition ( int axis ) ;
  210.  
  211.     remarks:    'axis' is a bit mask of a single active axis
  212.                 in original port format and may be specified
  213.                 with one of the following defined macros:
  214.  
  215.                     JAX_AXIS, JAY_AXIS, JBX_AXIS, JBY_AXIS
  216.  
  217.     returns:    the position of the given axis in the original
  218.                 coordinate system.  The values for a 100k
  219.                 joystick should be between 4 and 400, but may
  220.                 exceed these limits, especially with the
  221.                 adjustment sliders on most joysticks.
  222.  
  223. /*-------------------------------------------------------------------*/
  224.  
  225. JstGetValidAxes
  226.  
  227.     purpose:    returns a bit mask of the valid axes found by
  228.                 JstDetect() in original port format.
  229.  
  230.     syntax:     int  JstGetValidAxes ( void ) ;
  231.  
  232.     remarks:    intended to be use before an attempt to set the
  233.                 current active axis mask with JstSetActiveAxes().
  234.  
  235.     returns:    bit mask of valid axes in original port format.
  236.                 Values can be easily checked by ANDing this value
  237.                 with the defined macros:
  238.  
  239.                             JOYSTICK_A, JOYSTICK_B
  240.                     JAX_AXIS, JAY_AXIS, JBX_AXIS, JBY_AXIS
  241.     
  242. /*-------------------------------------------------------------------*/
  243.  
  244. JstGetActiveAxes
  245.  
  246.     purpose:    returns a bit mask of the currently active axes
  247.                 used in error checking by JstGetPosition() in
  248.                 original port format.
  249.  
  250.     syntax:     int  JstGetActiveAxes ( void ) ;
  251.  
  252.     remarks:    This mask is used to screen out possible calls
  253.                 to time axes that may be valid, but are not
  254.                 in use, thus saving precious cycles.
  255.  
  256.     returns:    bit mask of currently active axes in original port
  257.                 format. Values can be easily checked by ANDing this
  258.                 value with the defined macros:
  259.  
  260.                             JOYSTICK_A, JOYSTICK_B
  261.                     JAX_AXIS, JAY_AXIS, JBX_AXIS, JBY_AXIS
  262.     
  263.  
  264. /*-------------------------------------------------------------------*/
  265.  
  266. JstSetActiveAxes
  267.  
  268.     purpose:    sets valid axes for read operations by
  269.                 JstGetPosition().
  270.  
  271.     syntax:     int  JstSetActiveAxes ( unsigned mask ) ;
  272.  
  273.     remarks:    The value is written only if the entire given
  274.                 mask is valid.  Validity may be determined
  275.                 beforehand by getting a mask of valid axes
  276.                 with JstGetValidAxes().
  277.  
  278.     returns:    1 on success, 0 if mask is invalid.
  279.  
  280. /*-------------------------------------------------------------------*/
  281. /*------------------- Middle Level Functions ------------------------*/
  282. /*-------------------------------------------------------------------*/
  283.  
  284. JstInitialize
  285.                                                  
  286.     purpose:    to detect and initialize joysticks
  287.  
  288.     syntax:     int  JstInitialize ( void (*NotifyUserFunc)(int) ) ;
  289.  
  290.     remarks:    This function first calls JstDetect to determine
  291.                 if a joystick(s) is installed and set up valid and
  292.                 active joystick axis pairs.  It then calls the
  293.                 given user notification function NotifyUserFunc()
  294.                 to prompt the user to enter the center, minimum,
  295.                 and maximum joystick coordinate pairs.  At any
  296.                 point during the user data input step, the user
  297.                 may quit the process by pressing escape.  This
  298.                 function then calculates the starting ignore
  299.                 threshold (tolerance) and quasi linear scale for
  300.                 calls to JstGetChangedPosition().
  301.  
  302.                 NotifyUserFunc is a pointer to a user provided
  303.                 function which prompts the user for input during
  304.                 the intialization process.  It takes one parameter,
  305.                 an integer to determine what message to display.
  306.                 The function's format should be as follows...
  307.  
  308.         void NotifyUserFunc( int msg )
  309.         BEGIN
  310.         switch (msg)
  311.             case  -2: "warning: joystick installation incomplete"
  312.             case  -1: "joystick installation terminated by user"
  313.             case   0: "no joystick detected"
  314.             case   1: "press escape to quit"
  315.             case   2: "center joystick and press button"
  316.             case   3: "move joystick to top-left and press button 1"
  317.             case   4: "move joystick to lower-right and press button 2"
  318.             case  -3: return
  319.             default : return
  320.         END
  321.  
  322.     returns:    1 on success, 0 on failure
  323.  
  324. /*-------------------------------------------------------------------*/
  325.  
  326. JstGetChangedPosition
  327.  
  328.     purpose:    return position of given joystick if it has
  329.                 changed past the tolerance scale (ignore threshold).
  330.  
  331.     syntax:     int JstGetChangedPosition ( int stick,
  332.                                 struct JoystickPosition *stickpos ) ;
  333.  
  334.     remarks:    the tolerance scale is set to decrease from
  335.                 the maximum value as set by JstSetTolerance()
  336.                 and JstInitialize() at the bottom-right corner
  337.                 of the joystick through three asymetric steps
  338.                 set towards the upper-left corner.  This scale
  339.                 is intended to produces a more linear action
  340.                 across the span of the joystick with a minimum
  341.                 of calculation (time).
  342.  
  343.                 The value of 'stick' may be easily set with the
  344.                 defined macros JOYSTICK_A and JOYSTICK_B. The
  345.                 joystick position (if changed) is returned in
  346.                 the JoystickPosition structure 'stickpos'.
  347.                 The values in stickpos are undefined if the
  348.                 position has not changed.
  349.  
  350.     returns:    1 if 'stickpos' contains a new position.
  351.                 0 if no change.
  352.  
  353. /*-------------------------------------------------------------------*/
  354.  
  355. JstGetTolerance
  356.  
  357.     purpose:    return maxmimum value on the tolerance scale
  358.                 (ignore changed position threshold).
  359.  
  360.     syntax:     int  JstGetTolerance ( void ) ;
  361.  
  362.     remarks:    this value is originally set as the combined
  363.                 maximum joystick coordinates divided by 64 which
  364.                 should generally yield a value around 10.
  365.  
  366.     returns:    positive integer
  367.  
  368. /*-------------------------------------------------------------------*/
  369.  
  370. JstSetTolerance
  371.  
  372.     purpose:    sets the tolerance value (ignore changed position
  373.                 threshold) for the top of the scale at the
  374.                 joystick's bottom-right for JstGetChangedPosition()
  375.  
  376.     syntax:     void JstSetTolerance ( int tolerance ) ;
  377.  
  378.     remarks:    this value is originally set as the combined
  379.                 maximum joystick coordinates divided by 64 which
  380.                 should generally yield a value around 10.
  381.  
  382.     returns:    void
  383.  
  384. /*-------------------------------------------------------------------*/
  385.  
  386. JstSetCenter
  387.  
  388.     purpose:    grabs the current coordinates of the given joystick
  389.                 and set the center of the cartesian system to that
  390.                 point. It also resets the tolerance scale.
  391.  
  392.     syntax:     int  JstSetCenter ( int stick ) ;
  393.  
  394.     remarks:    The value of 'stick' may be easily set with the
  395.                 defined macros JOYSTICK_A and JOYSTICK_B. 
  396.  
  397.     returns:    1 on success, 0 if invalid joystick.
  398.  
  399. /*-------------------------------------------------------------------*/
  400.  
  401. JstSetMin
  402.  
  403.     purpose:    grabs the current coordinates of the given joystick
  404.                 and stores it as the minimum joystick position.
  405.                 It also resets the tolerance scale.
  406.  
  407.     syntax:     int  JstSetMin ( int stick ) ;
  408.  
  409.     remarks:    The value of 'stick' may be easily set with the
  410.                 defined macros JOYSTICK_A and JOYSTICK_B. 
  411.  
  412.     returns:    1 on success, 0 if invalid joystick.
  413.  
  414. /*-------------------------------------------------------------------*/
  415.  
  416. JstSetMax
  417.  
  418.     purpose:    grabs the current coordinates of the given joystick
  419.                 and stores it as the maximum joystick position.
  420.                 It also resets the tolerance scale.
  421.  
  422.     syntax:     int  JstSetMax ( int stick ) ;
  423.  
  424.     remarks:    The value of 'stick' may be easily set with the
  425.                 defined macros JOYSTICK_A and JOYSTICK_B.
  426.  
  427.     returns:    1 on success, 0 if invalid joystick.
  428.  
  429. /*-------------------------------------------------------------------*/
  430.  
  431. JstGetCenter
  432.  
  433.     purpose:    returns the current coordinates of the set
  434.                 center position of the given joystick.
  435.  
  436.     syntax:     void JstGetCenter( int stick,
  437.                                 struct JoystickPosition *jpos ) ;
  438.  
  439.     remarks:    The value of 'stick' may be easily set with the
  440.                 defined macros JOYSTICK_A and JOYSTICK_B.
  441.  
  442.     returns:    void
  443.  
  444. /*-------------------------------------------------------------------*/
  445.  
  446. JstGetMin
  447.  
  448.     purpose:    returns the current coordinates of the set
  449.                 minimum position of the given joystick.
  450.  
  451.     syntax:     void JstGetMin ( int stick,
  452.                                 struct JoystickPosition *jpos ) ;
  453.  
  454.     remarks:    The value of 'stick' may be easily set with the
  455.                 defined macros JOYSTICK_A and JOYSTICK_B.
  456.  
  457.     returns:    void
  458.  
  459. /*-------------------------------------------------------------------*/
  460.  
  461. JstGetMax
  462.  
  463.     purpose:    returns the current coordinates of the set
  464.                 center position of the given joystick.
  465.  
  466.     syntax:     void JstGetMax ( int stick,
  467.                                 struct JoystickPosition *jpos ) ;
  468.  
  469.     remarks:    The value of 'stick' may be easily set with the
  470.                 defined macros JOYSTICK_A and JOYSTICK_B.
  471.  
  472.     returns:    void
  473.  
  474. /*-------------------------------------------------------------------*/
  475.  
  476. JstXlatToCart
  477.  
  478.     purpose:    translate the given coordinates from real to
  479.                 cartesian coordinates.
  480.  
  481.     syntax:     void JstXlatToCart ( int stick,
  482.                                 struct JoystickPosition *stickpos ) ;
  483.  
  484.     remarks:    'stickpos' contains the real coordinates to be
  485.                 translated and returns cartesian values based on
  486.                 the set center of the joystick 'stick'.
  487.  
  488.     returns:    void
  489.  
  490. /*-------------------------------------------------------------------*/
  491.  
  492. /*-- end joystick.doc */
  493.                                      
  494.